Skip to main content

FF-API-External Documentation

Introduction​

FF-API-External is a Flask-based API service that handles all 3rd party integrations for the FeelyFeely platform, with the exception of payments, communications, messaging, and social media. This documentation covers the architecture, setup, and available endpoints of the API service.

Table of Contents​

  1. Overview
  2. Getting Started
  3. Architecture
  4. Available API Endpoints
  5. Database Integrations
  6. Third-Party Services
  7. Security Considerations
  8. Deployment
  9. Troubleshooting
  10. Contributing

Overview​

FF-API-External serves as a central hub for integrating with various third-party services and APIs. The service is designed to provide a unified interface for accessing external data sources and services, making it easier to incorporate these functionalities into the FeelyFeely platform.

The service includes integrations with:

  • AI services (OpenAI, Claude)
  • Vehicle information services
  • Mobile device information services
  • SERP (Search Engine Results Page) APIs
  • Payment processing
  • Geolocation services
  • And many others

Getting Started​

Prerequisites​

To run this service, you need:

  • Python 3.11.9 (as specified in runtime.txt)
  • MySQL database
  • MongoDB database
  • Various API keys (specified in .env)

Installation​

  1. Clone the repository:

    git clone <repository-url>
    cd ff-api-external

  2. Create and activate a virtual environment:

    python -m venv venv
    source venv/bin/activate  # On Windows, use: venv\Scripts\activate

  3. Install dependencies:

    pip install -r requirements.txt

Configuration​

The service uses environment variables for configuration. Create a .env file in the root directory with the following variables (as shown in the provided .env file):

# Database configurations
MYSQL_HOST=your-mysql-host
MYSQL_USER=your-mysql-user
MYSQL_PASSWORD=your-mysql-password
MYSQL_DB=your-mysql-db
MYSQL_CURSORCLASS=DictCursor
MYSQL_PORT=your-mysql-port

# MongoDB configurations
MONGODB_MAIN_PROD=your-mongodb-connection-string

# API keys for various services
CHAT_GPT_API_KEY=your-openai-api-key
CLAUDE_API_KEY=your-claude-api-key
# ... other API keys as needed

🔒 Security Note: Never commit your .env file to version control. Make sure it's listed in your .gitignore file.

Architecture​

Project Structure​

The project follows a modular structure:

  • /app.py - Main Flask application initialization
  • /server.py - Server configuration and API route registration
  • /utils/ - Utility functions and common helpers
  • /models/ - Service models and business logic
  • /view/api/ - API route definitions
  • /dbutils/ - Database utility functions